From 7977b62ae2b56a4ef73ea37659031d96d49f3333 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Tue, 20 May 2008 07:48:30 +0000 Subject: [PATCH] More interface header reviews by Azriel Fasten, and added skeleton docs for wxBookCtrlBase (still needs docs though). git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53665 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/bookctrl.h | 25 ++ interface/toolbar.h | 392 +++++++++++++--------- interface/tracker.h | 18 +- interface/treebase.h | 104 +++++- interface/treebook.h | 182 ++++++---- interface/treectrl.h | 778 +++++++++++++++++++++++-------------------- interface/txtstrm.h | 190 ++++++----- 7 files changed, 1000 insertions(+), 689 deletions(-) create mode 100644 interface/bookctrl.h diff --git a/interface/bookctrl.h b/interface/bookctrl.h new file mode 100644 index 0000000000..c4d68d7bdf --- /dev/null +++ b/interface/bookctrl.h @@ -0,0 +1,25 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bookctrl.h +// Purpose: interface of wxBookCtrlBase +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBookCtrlBase + @wxheader{bookctrl.h} + + @todo Document this class. + + @library{wxcore} + @category{miscwnd} + + @see @ref overview_bookctrl +*/ +class wxBookCtrlBase : public wxControl +{ +public: + +}; + diff --git a/interface/toolbar.h b/interface/toolbar.h index 7c7714b9af..72e8ecebb5 100644 --- a/interface/toolbar.h +++ b/interface/toolbar.h @@ -10,49 +10,123 @@ @class wxToolBar @wxheader{toolbar.h} - The name wxToolBar is defined to be a synonym for one of the following classes: - - @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. - + The name wxToolBar is defined to be a synonym for one of the following + classes: + + - @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 + 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. + To do this, set the msw.remap system option before creating the toolbar: + + @code + wxSystemOptions::SetOption(wxT("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); + @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). + Gives the toolbar a flat look (Windows and GTK only). @style{wxTB_DOCKABLE} - Makes the toolbar floatable and dockable (GTK only). + Makes the toolbar floatable and dockable (GTK only). @style{wxTB_HORIZONTAL} - Specifies horizontal layout (default). + Specifies horizontal layout (default). @style{wxTB_VERTICAL} - Specifies vertical layout. + Specifies vertical layout. @style{wxTB_TEXT} - Shows the text in the toolbar buttons; by default only icons are - shown. + Shows the text in the toolbar buttons; by default only icons are shown. @style{wxTB_NOICONS} - Specifies no icons in the toolbar buttons; by default they are - shown. + Specifies no icons in the toolbar buttons; by default they are shown. @style{wxTB_NODIVIDER} - Specifies no divider (border) above the toolbar (Windows only). + Specifies no divider (border) above the toolbar (Windows only) @style{wxTB_NOALIGN} - Specifies no alignment with the parent window (Windows only, not - very useful). + Specifies no alignment with the parent window (Windows only, not very + useful). @style{wxTB_HORZ_LAYOUT} - Shows the text and the icons alongside, not vertically stacked - (Windows and GTK 2 only). This style must be used with wxTB_TEXT. + Shows the text and the icons alongside, not vertically stacked (Windows + and GTK 2 only). This style must be used with @c wxTB_TEXT. @style{wxTB_HORZ_TEXT} - Combination of wxTB_HORZ_LAYOUT and wxTB_TEXT. + Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT. @style{wxTB_NO_TOOLTIPS} - Don't show the short help tooltips for the tools when the mouse - hovers over them. + Don't show the short help tooltips for the tools when the mouse hovers + over them. @style{wxTB_BOTTOM} - Align the toolbar at the bottom of parent window. + Align the toolbar at the bottom of parent window. @style{wxTB_RIGHT} - Align the toolbar at the right side of parent window. + Align the toolbar at the right side of parent window. @endStyleTable - @library{wxbase} + See also @ref overview_windowstyles. Note that the Win32 native toolbar + ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only + if the style was initially on. + + @beginEventTable{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. + @event{EVT_MENU(id, func)} + The same as EVT_TOOL(). + @event{EVT_TOOL_RANGE(id1, id2, func)} + Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of + identifiers. Pass the ids of the tools. + @event{EVT_MENU_RANGE(id1, id2, func)} + 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. + @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. + @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. + @event{EVT_TOOL_DROPDOWN(id, func)} + Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled, + 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 + system. + + @library{wxcore} @category{miscwnd} @see @ref overview_toolbar @@ -60,7 +134,11 @@ class wxToolBar : public wxControl { public: - //@{ + /** + Default constructor. + */ + wxToolBar(); + /** Constructs a toolbar. @@ -69,31 +147,26 @@ 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 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. @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets - should generate a default size for the window. + Window size. ::wxDefaultSize is (-1, -1) which indicates that + wxWidgets should generate a default size for the window. @param style Window style. See wxToolBar 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. + @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. */ - wxToolBar(); wxToolBar(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxTB_HORIZONTAL | wxBORDER_NONE, const wxString& name = wxPanelNameStr); - //@} /** Toolbar destructor. @@ -101,8 +174,8 @@ public: ~wxToolBar(); /** - Adds a new check (or toggle) tool to the toolbar. The parameters are the same - as in AddTool(). + Adds a new check (or toggle) tool to the toolbar. The parameters are the + same as in AddTool(). @see AddTool() */ @@ -115,26 +188,34 @@ public: wxObject* clientData = NULL); /** - Adds any control to the toolbar, typically e.g. a combobox. + Adds any control to the toolbar, typically e.g. a wxComboBox. @param control The control to be added. @param label Text to be displayed near the control. - @remarks wxMSW: the label is only displayed if there is enough space - available below the embedded control. + @remarks + wxMSW: the label is only displayed if there is enough space + available below the embedded control. + + @remarks + 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 = ""); /** - 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. + 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. + @see AddTool() */ @@ -155,40 +236,39 @@ public: //@{ /** - 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 - you to add an existing 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 you to add an existing tool. @param toolId - An integer by which - the tool may be identified in subsequent operations. + An integer by which the tool may be identified in subsequent + operations. @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 - 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 + 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. @param bitmap1 The primary tool bitmap. @param bitmap2 The bitmap used when the tool is disabled. If it is equal to - wxNullBitmap, the disabled bitmap is automatically generated by greing the - normal one. + ::wxNullBitmap, the disabled bitmap is automatically generated by + greying the normal one. @param shortHelpString - This string is used for the tools tooltip + 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 + 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(). + An optional pointer to client data which can be retrieved later + using GetToolClientData(). @param tool 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() @@ -213,20 +293,22 @@ public: void ClearTools(); /** - Removes the specified tool from the toolbar and deletes it. If you don't want - to delete the tool, but just to remove it from the toolbar (to possibly add it - back later), you may use RemoveTool() instead. - Note that it is unnecessary to call Realize() for the - change to take place, it will happen immediately. - Returns @true if the tool was deleted, @false otherwise. + Removes the specified tool from the toolbar and deletes it. If you don't + want to delete the tool, but just to remove it from the toolbar (to + possibly add it back later), you may use RemoveTool() instead. + + @note It is unnecessary to call Realize() for the change to take + place, it will happen immediately. + + @returns @true if the tool was deleted, @false otherwise. @see DeleteToolByPos() */ 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. + 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); @@ -239,21 +321,22 @@ public: If @true, enables the tool, otherwise disables it. @remarks Some implementations will change the visible state of the tool - to indicate that it is disabled. + to indicate that it is disabled. + @see GetToolEnabled(), ToggleTool() */ void EnableTool(int toolId, bool enable); /** - Returns a pointer to the tool identified by @a id or - @NULL if no corresponding tool is found. + Returns a pointer to the tool identified by @a id or @NULL if no + corresponding tool is found. */ wxToolBarToolBase* FindById(int id); /** - Returns a pointer to the control identified by @a id or - @NULL if no corresponding control is found. + Returns a pointer to the control identified by @a id or @NULL if no + corresponding control is found. */ wxControl* FindControl(int id); @@ -267,7 +350,8 @@ public: @return A pointer to a tool if a tool is found, or @NULL otherwise. - @remarks Currently not implemented in wxGTK (always returns @NULL there). + @remarks Currently not implemented in wxGTK (always returns @NULL + there). */ wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const; @@ -280,12 +364,11 @@ 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 16 by 15 pixels. - @remarks Note that this is the size of the bitmap you pass to - AddTool(), and not the eventual size of the - tool button. + @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() */ @@ -331,8 +414,8 @@ public: int GetToolPacking() const; /** - Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool is not - found. + Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool + is not found. */ int GetToolPos(int toolId) const; @@ -354,9 +437,8 @@ public: wxString GetToolShortHelp(int toolId) const; /** - Returns the size of a whole button, which is usually larger than a tool bitmap - because - of added 3D effects. + Returns the size of a whole button, which is usually larger than a tool + bitmap because of added 3D effects. @see SetToolBitmapSize(), GetToolBitmapSize() */ @@ -380,16 +462,16 @@ public: int GetToolsCount() const; /** - Inserts the control into the toolbar at the given position. - You must call Realize() for the change to take place. + Inserts the control into the toolbar at the given position. You must + call Realize() for the change to take place. @see AddControl(), InsertTool() */ wxToolBarToolBase* InsertControl(size_t pos, wxControl* control); /** - Inserts the separator into the toolbar at the given position. - You must call Realize() for the change to take place. + Inserts the separator into the toolbar at the given position. You must + call Realize() for the change to take place. @see AddSeparator(), InsertTool() */ @@ -397,8 +479,9 @@ public: //@{ /** - Inserts the tool with the specified attributes into the toolbar at the given - position. + Inserts the tool with the specified attributes into the toolbar at the + given position. + You must call Realize() for the change to take place. @see AddTool(), InsertControl(), InsertSeparator() @@ -415,49 +498,50 @@ public: //@} /** - Called when the user clicks on a tool with the left mouse button. - This is the old way of detecting tool clicks; although it will still work, - you should use the EVT_MENU or EVT_TOOL macro instead. + Called when the user clicks on a tool with the left mouse button. This + is the old way of detecting tool clicks; although it will still work, + you should use the EVT_MENU() or EVT_TOOL() macro instead. @param toolId The identifier passed to AddTool(). @param toggleDown - @true if the tool is a toggle and the toggle is down, otherwise is @false. + @true if the tool is a toggle and the toggle is down, otherwise is + @false. @return 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. + toggle state (internal and visual) will not be changed. This + provides a way of specifying that toggle operations are not + permitted in some circumstances. @see OnMouseEnter(), OnRightClick() */ bool OnLeftClick(int toolId, bool toggleDown); /** - This is called when the mouse cursor moves into a tool or out of - the toolbar. - This is the old way of detecting mouse enter events; although it will still - work, - you should use the EVT_TOOL_ENTER macro instead. + This is called when the mouse cursor moves into a tool or out of the + toolbar. This is the old way of detecting mouse enter events; + although it will still work, you should use the EVT_TOOL_ENTER() + macro instead. @param toolId - Greater than -1 if the mouse cursor has moved into the tool, - or -1 if the mouse cursor has moved. The - programmer can override this to provide extra information about the tool, - such as a short description on the status line. + Greater than -1 if the mouse cursor has moved into the tool, or -1 + if the mouse cursor has moved. The programmer can override this to + provide extra information about the tool, such as a short + description on the status line. @remarks With some derived toolbar classes, if the mouse moves quickly - out of the toolbar, wxWidgets may not be able to detect - it. Therefore this function may not always be called - when expected. + 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); /** + @deprecated This is the old way of detecting tool right clicks; + although it will still work, you should use the + EVT_TOOL_RCLICKED() macro instead. + Called when the user clicks on a tool with the right mouse button. The programmer should override this function to detect right tool clicks. - This is the old way of detecting tool right clicks; although it will still work, - you should use the EVT_TOOL_RCLICKED macro instead. @param toolId The identifier passed to AddTool(). @@ -478,26 +562,29 @@ public: bool Realize(); /** - Removes the given tool from the toolbar but doesn't delete it. This allows to - insert/add this tool back to this (or another) toolbar later. - Note that it is unnecessary to call Realize() for the - change to take place, it will happen immediately. + Removes the given tool from the toolbar but doesn't delete it. This + allows to insert/add this tool back to this (or another) toolbar later. + + @note It is unnecessary to call Realize() for the change to take place, + it will happen immediately. + @see DeleteTool() */ wxToolBarToolBase* RemoveTool(int id); /** - Sets the bitmap resource identifier for specifying tool bitmaps as indices - into a custom bitmap. Windows CE only. + Sets the bitmap resource identifier for specifying tool bitmaps as + indices into a custom bitmap. Windows CE only. */ void SetBitmapResource(int resourceId); /** - Sets the dropdown menu for the tool given by its @e id. The tool itself will - delete the menu when it's no longer needed. - If you define a EVT_TOOL_DROPDOWN handler in your program, you must call - wxEvent::Skip from it or the menu won't be displayed. + Sets the dropdown menu for the tool given by its @e id. The tool itself + will delete the menu when it's no longer needed. + + If you define a EVT_TOOL_DROPDOWN() handler in your program, you must + call wxEvent::Skip() from it or the menu won't be displayed. */ bool SetDropdownMenu(int id, wxMenu* menu); @@ -513,8 +600,8 @@ public: Top margin, bottom margin and inter-tool separation value. @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. + positioning is to be used, and the default (zero-size) margins are + to be overridden. @see GetMargins(), wxSize */ @@ -523,14 +610,14 @@ public: //@} /** - Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 - pixels. + Sets the default size of each tool bitmap. The default bitmap size is 16 + by 15 pixels. @param size The size of the bitmaps in the toolbar. @remarks This should be called to tell the toolbar what the tool bitmap - size is. Call it before you add tools. + size is. Call it before you add tools. @see GetToolBitmapSize(), GetToolSize() */ @@ -543,10 +630,13 @@ public: /** Sets the bitmap to be used by the tool with the given ID when the tool - is in a disabled state. This can only be used on Button tools, not - controls. 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. + is in a disabled state. This can only be used on Button tools, not + controls. + + @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. + */ void SetToolDisabledBitmap(int id, const wxBitmap& bitmap); @@ -559,15 +649,15 @@ public: A string for the long help. @remarks You might use the long help for displaying the tool purpose on - the status line. + the status line. @see GetToolLongHelp(), SetToolShortHelp(), */ 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. + 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); @@ -577,9 +667,9 @@ public: @param packing The value for packing. - @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. + @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() */ @@ -604,7 +694,8 @@ public: The string for the short help. @remarks An application might use short help for identifying the tool - purpose in a tooltip. + purpose in a tooltip. + @see GetToolShortHelp(), SetToolLongHelp() */ @@ -618,7 +709,8 @@ public: @param toggle If @true, toggles the tool on, otherwise toggles it off. - @remarks Only applies to a tool that has been specified as a toggle tool. + @remarks Only applies to a tool that has been specified as a toggle + tool. */ void ToggleTool(int toolId, bool toggle); }; diff --git a/interface/tracker.h b/interface/tracker.h index 64484b10d1..67d4bc0a65 100644 --- a/interface/tracker.h +++ b/interface/tracker.h @@ -10,25 +10,23 @@ @class wxTrackable @wxheader{tracker.h} - Add-on base class for a trackable object. This class maintains - an internal linked list of classes of type wxTrackerNode and - calls OnObjectDestroy() on them if this object is destroyed. - The most common usage is by using the wxWeakRefT() - class template which automates this. This class has no public - API. Its only use is by deriving another class from it to - make it trackable. + Add-on base class for a trackable object. This class maintains an internal + linked list of classes of type wxTrackerNode and calls OnObjectDestroy() on + them if this object is destroyed. The most common usage is by using the + wxWeakRef class template which automates this. This class has no public + API. Its only use is by deriving another class from it to make it trackable. @code class MyClass: public Foo, public wxTrackable { - // whatever + // whatever } - typedef wxWeakRefMyClass MyClassRef; + typedef wxWeakRef MyClassRef; @endcode @library{wxbase} - @category{FIXME} + @category{smartpointers} */ class wxTrackable { diff --git a/interface/treebase.h b/interface/treebase.h index 9e83d58c79..84ffd78598 100644 --- a/interface/treebase.h +++ b/interface/treebase.h @@ -13,18 +13,17 @@ An opaque reference to a tree item. @library{wxcore} - @category{FIXME} + @category{misc} - @see wxTreeCtrl, wxTreeItemData, @ref overview_wxtreectrloverview "wxTreeCtrl - overview" + @see wxTreeCtrl, wxTreeItemData, @ref overview_treectrl */ class wxTreeItemId { public: /** - Default constructor. wxTreemItemIds are not meant to be constructed explicitly - by - the user; they are returned by the wxTreeCtrl functions instead. + Default constructor. A wxTreeItemId is not meant to be constructed + explicitly by the user; only those returned by the wxTreeCtrl functions + should be used. */ wxTreeItemId(); @@ -35,11 +34,96 @@ public: //@{ /** - Operators for comparison between wxTreeItemId objects. + Operators for comparison between wxTreeItemId objects. */ - void operator !() const; - const bool operator ==(const wxTreeItemId& item) const; - const bool operator !=(const wxTreeItemId& item) const; + bool operator ==(const wxTreeItemId& item) const; + bool operator !=(const wxTreeItemId& item) const; //@} + + /** + Antonym of IsOk(), i.e. returns @true only if the item is not valid. + */ + bool operator !() const; }; +/** + @class wxTreeItemData + @wxheader{treebase.h} + + wxTreeItemData is some (arbitrary) user class associated with some item. The + main advantage of having this class is that wxTreeItemData objects are + destroyed automatically by the tree and, as this class has virtual + destructor, it means that the memory and any other resources associated with + a tree item will be automatically freed when it is deleted. Note that we + don't use wxObject as the base class for wxTreeItemData because the size of + this class is critical: in many applications, each tree leaf will have + wxTreeItemData associated with it and the number of leaves may be quite big. + + Also please note that because the objects of this class are deleted by the + tree using the operator @c delete, they must always be allocated on the heap + using @c new. + + @library{wxcore} + @category{containers} + + @see wxTreeCtrl +*/ +class wxTreeItemData : public wxClientData +{ +public: + /** + Default constructor. + + @beginWxPythonOnly + The following methods are added in wxPython for accessing the object: + - GetData(): Returns a reference to the Python Object. + - SetData(obj): Associates a new Python Object with the wxTreeItemData. + @endWxPythonOnly + */ + wxTreeItemData(); + + /** + Virtual destructor. + */ + ~wxTreeItemData(); + + /** + Returns the item associated with this node. + */ + const wxTreeItemId GetId(); + + /** + Sets the item associated with this node. + */ + void SetId(const wxTreeItemId& id); +}; + +/** + Indicates which type to associate an image with a wxTreeCtrl item. + + @see wxTreeCtrl::GetItemImage(), wxTreeCtrl::SetItemImage() +*/ +enum wxTreeItemIcon +{ + /** + To get/set the item image for when the item is + @b not selected and @b not expanded. + */ + wxTreeItemIcon_Normal, + /** + To get/set the item image for when the item is + @b selected and @b not expanded. + */ + wxTreeItemIcon_Selected, + /** + To get/set the item image for when the item is + @b not selected and @b expanded. + */ + wxTreeItemIcon_Expanded, + /** + To get/set the item image for when the item is + @b selected and @b expanded. + */ + wxTreeItemIcon_SelectedExpanded, + wxTreeItemIcon_Max +}; diff --git a/interface/treebook.h b/interface/treebook.h index 524c819b4c..c950031b2d 100644 --- a/interface/treebook.h +++ b/interface/treebook.h @@ -11,20 +11,34 @@ @wxheader{treebook.h} This class represents the events generated by a treebook control: currently, - there are four of them. The PAGE_CHANGING and PAGE_CHANGED - have exactly the - same - behaviour as wxNotebookEvent. - - The other two NODE_COLLAPSED and NODE_EXPANDED are triggered when page node in - the tree control - is collapsed/expanded. The page index could be retreived by calling - wxTreebookEvent::GetSelection. - - + there are four of them. The EVT_TREEBOOK_PAGE_CHANGING() and + EVT_TREEBOOK_PAGE_CHANGED() - have exactly the same behaviour as + wxNotebookEvent. + + The other two EVT_TREEBOOK_NODE_COLLAPSED() and EVT_TREEBOOK_NODE_EXPANDED() + are triggered when page node in the tree control is collapsed/expanded. The + page index could be retreived by calling GetSelection(). + + @beginEventTable{wxTreebookEvent} + @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)} + The page selection was changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event. + @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)} + The page selection is about to be changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref + wxNotifyEvent::Veto() "vetoed". + @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)} + The page node is going to be collapsed. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event. + @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)} + The page node is going to be expanded. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event. + @endEventTable + @library{wxcore} @category{events} - @see wxNotebookEvent, wxTreebook + @see wxTreebook, wxNotebookEvent */ class wxTreebookEvent : public wxNotifyEvent { @@ -37,13 +51,16 @@ public: int nOldSel = wxNOT_FOUND); /** - Returns the page that was selected before the change, wxNOT_FOUND if none was - selected. + Returns the page that was selected before the change, @c wxNOT_FOUND if + none was selected. */ int GetOldSelection() const; /** - Returns the currently selected page, or wxNOT_FOUND if none was selected. + Returns the currently selected page, or @c wxNOT_FOUND if none was + selected. + + @see wxNotebookEvent::GetSelection() */ int GetSelection() const; }; @@ -54,34 +71,50 @@ public: @class wxTreebook @wxheader{treebook.h} - This class is an extension of the Notebook class that allows a tree structured - set of pages to be shown in a control. - A classic example is a netscape preferences dialog that shows a tree - of preference sections on the left and select section page on the right. + This class is an extension of the wxNotebook class that allows a tree + structured set of pages to be shown in a control. A classic example is a + netscape preferences dialog that shows a tree of preference sections on + the left and select section page on the right. To use the class simply create it and populate with pages using - wxTreebook::InsertPage, - wxTreebook::InsertSubPage, - wxTreebook::AddPage, - wxTreebook::AddSubPage. - - If your tree is no more than 1 level in depth then you could - simply use wxTreebook::AddPage and - wxTreebook::AddSubPage to sequentially populate your tree - by adding at every step a page or a subpage to the end of the tree. + InsertPage(), InsertSubPage(), AddPage(), AddSubPage(). + + If your tree is no more than 1 level in depth then you could simply use + AddPage() and AddSubPage() to sequentially populate your tree by adding at + every step a page or a subpage to the end of the tree. + + @beginEventTable{wxTreebookEvent} + @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)} + The page selection was changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event. + @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)} + The page selection is about to be changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref + wxNotifyEvent::Veto() "vetoed". + @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)} + The page node is going to be collapsed. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event. + @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)} + The page node is going to be expanded. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event. + @endEventTable @library{wxcore} @category{miscwnd} - @see wxNotebook, wxTreebookEvent, wxImageList, @ref overview_samplenotebook - "notebook sample" + @see wxTreebookEvent, wxNotebook, wxTreeCtrl, wxImageList, + @ref overview_bookctrl, @ref page_samples_notebook */ -class wxTreebook : public wxBookCtrl overview +class wxTreebook : public wxBookCtrlBase { public: - //@{ /** - Creates an empty TreeBook control. + Default constructor. + */ + wxTreebook(); + + /** + Creates an empty wxTreebook. @param parent The parent window. Must be non-@NULL. @@ -96,59 +129,61 @@ public: @param name The name of the control (used only under Motif). */ - wxTreebook(); wxTreebook(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxBK_DEFAULT, const wxString& name = wxEmptyString); - //@} /** - Destroys the wxTreebook object. - Also deletes all the pages owned by the control (inserted previously into it). + Destroys the wxTreebook object. Also deletes all the pages owned by the + control (inserted previously into it). */ ~wxTreebook(); /** - Adds a new page. The page is placed at the topmost level after all other pages. - @NULL could be specified for page to create an empty page. + Adds a new page. The page is placed at the topmost level after all other + pages. @NULL could be specified for page to create an empty page. */ bool AddPage(wxWindow* page, const wxString& text, bool bSelect = false, int imageId = wxNOT_FOUND); /** - Adds a new child-page to the last top-level page. - @NULL could be specified for page to create an empty page. + Adds a new child-page to the last top-level page. @NULL could be + specified for page to create an empty page. */ bool AddSubPage(wxWindow* page, const wxString& text, bool bSelect = false, int imageId = wxNOT_FOUND); /** - Sets the image list for the page control and takes ownership of the list. + Sets the image list for the page control and takes ownership of the + list. @see wxImageList, SetImageList() */ void AssignImageList(wxImageList* imageList); /** - Changes the selection for the given page, returning the previous selection. + Changes the selection for the given page, returning the previous + selection. + The call to this function does not generate the page changing events. - This is the only difference with SetSelection(). - See @ref overview_progevent "this topic" for more info. + This is the only difference with SetSelection(). See + @ref overview_eventhandling_prog for more info. */ int ChangeSelection(size_t page); /** - Shortcut for wxTreebook::ExpandNode(pageId, @false). + Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId, + @false ). */ bool CollapseNode(size_t pageId); /** - Creates a treebook control. See wxTreebook() for the description of the - parameters. + Creates a treebook control. See wxTreebook::wxTreebook() for the + description of the parameters. */ bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, @@ -162,17 +197,16 @@ public: bool DeleteAllPages(); /** - Deletes the page at the specified position and all its children. Could trigger - page selection change - in a case when selected page is removed. In that case its parent is selected - (or the next page if no parent). + Deletes the page at the specified position and all its children. Could + trigger page selection change in a case when selected page is removed. + In that case its parent is selected (or the next page if no parent). */ bool DeletePage(size_t pagePos); /** - Expands (collapses) the pageId node. Returns the previous state. - May generate page changing events (if selected page - is under the collapsed branch, then its parent is autoselected). + Expands (collapses) the @a pageId node. Returns the previous state. May + generate page changing events (if selected page is under the collapsed + branch, then its parent is autoselected). */ bool ExpandNode(size_t pageId, bool expand = true); @@ -193,18 +227,20 @@ public: wxString GetPageText(size_t n) const; /** - Returns the currently selected page, or wxNOT_FOUND if none was selected. - Note that this method may return either the previously or newly selected page - when called from the EVT_TREEBOOK_PAGE_CHANGED handler - depending on the platform and so wxTreebookEvent::GetSelection should be used - instead in this case. + Returns the currently selected page, or @c wxNOT_FOUND if none was + selected. + + @note This method may return either the previously or newly selected + page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler + depending on the platform and so wxTreebookEvent::GetSelection() + should be used instead in this case. */ int GetSelection() const; /** - Inserts a new page just before the page indicated by pagePos. - The new page is placed before pagePos page and on the same level. - @NULL could be specified for page to create an empty page. + Inserts a new page just before the page indicated by @a pagePos. The new + page is placed before @a pagePos page and on the same level. @NULL could + be specified for page to create an empty page. */ bool InsertPage(size_t pagePos, wxWindow* page, const wxString& text, @@ -213,6 +249,7 @@ public: /** Inserts a sub page under the specified page. + @NULL could be specified for page to create an empty page. */ bool InsertSubPage(size_t pagePos, wxWindow* page, @@ -221,36 +258,37 @@ public: int imageId = wxNOT_FOUND); /** - Gets the pagePos page state -- whether it is expanded or collapsed + Returns @true if the page represented by @a pageId is expanded. */ bool IsNodeExpanded(size_t pageId) const; /** - Sets the image list for the page control. It does not take ownership of the - image list, you must delete it yourself. + Sets the image list for the page control. It does not take ownership of + the image list, you must delete it yourself. @see wxImageList, AssignImageList() */ void SetImageList(wxImageList* imageList); /** - Sets the image index for the given page. ImageId is an index into the image list - which was set with SetImageList(). + Sets the image index for the given @a page. @a imageId is an index into + the image list which was set with SetImageList(). */ bool SetPageImage(size_t page, int imageId); /** - Sets the text for the given page. + Sets the @a text for the given @a page. */ bool SetPageText(size_t page, const wxString& text); /** + @deprecated Please use ChangeSelection() instead. + Sets the selection for the given page, returning the previous selection. - The call to this function generates the page changing events. - This function is deprecated and should not be used in new code. Please use the - ChangeSelection() function instead. - @see GetSelection() + The call to this function generates page changing events. + + @see GetSelection(), ChangeSelection() */ int SetSelection(size_t n); }; diff --git a/interface/treectrl.h b/interface/treectrl.h index 42476c50f5..1e560475ce 100644 --- a/interface/treectrl.h +++ b/interface/treectrl.h @@ -6,142 +6,97 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/** - @class wxTreeItemData - @wxheader{treectrl.h} - - wxTreeItemData is some (arbitrary) user class associated with some item. The - main advantage of having this class is that wxTreeItemData objects are - destroyed automatically by the tree and, as this class has virtual destructor, - it means that the memory and any other resources associated with a tree item - will be automatically freed when it is deleted. Note that we don't use wxObject - as the base class for wxTreeItemData because the size of this class is - critical: in many applications, each tree leaf will have wxTreeItemData - associated with it and the number of leaves may be quite big. - - Also please note that because the objects of this class are deleted by the tree - using the operator @c delete, they must always be allocated on the heap - using @c new. - - @library{wxcore} - @category{FIXME} - - @see wxTreeCtrl -*/ -class wxTreeItemData : public wxClientData -{ -public: - /** - Default constructor. - - In addition, the following methods are added in wxPython for accessing - the object: - - @b GetData() - - Returns a reference to the Python Object - - @b SetData(obj) - - Associates a new Python Object with the - wxTreeItemData - */ - wxTreeItemData(); - - /** - Virtual destructor. - */ - ~wxTreeItemData(); - - /** - Returns the item associated with this node. - */ - const wxTreeItemId GetId(); - - /** - Sets the item associated with this node. - */ - void SetId(const wxTreeItemId& id); -}; - - /** @class wxTreeCtrl @wxheader{treectrl.h} A tree control presents information as a hierarchy, with items that may be - expanded - to show further items. Items in a tree control are referenced by wxTreeItemId - handles, - which may be tested for validity by calling wxTreeItemId::IsOk. + expanded to show further items. Items in a tree control are referenced by + wxTreeItemId handles, which may be tested for validity by calling + wxTreeItemId::IsOk(). - To intercept events from a tree control, use the event table macros described - in wxTreeEvent. + To intercept events from a tree control, use the event table macros + described in wxTreeEvent. @beginStyleTable @style{wxTR_EDIT_LABELS} - Use this style if you wish the user to be able to edit labels in - the tree control. + Use this style if you wish the user to be able to edit labels in the + tree control. @style{wxTR_NO_BUTTONS} - For convenience to document that no buttons are to be drawn. + For convenience to document that no buttons are to be drawn. @style{wxTR_HAS_BUTTONS} - Use this style to show + and - buttons to the left of parent items. + Use this style to show + and - buttons to the left of parent items. @style{wxTR_NO_LINES} - Use this style to hide vertical level connectors. + Use this style to hide vertical level connectors. @style{wxTR_FULL_ROW_HIGHLIGHT} - Use this style to have the background colour and the selection - highlight extend over the entire horizontal row of the tree control - window. (This flag is ignored under Windows unless you specify - wxTR_NO_LINES as well.) + Use this style to have the background colour and the selection highlight + extend over the entire horizontal row of the tree control window. (This + flag is ignored under Windows unless you specify @c wxTR_NO_LINES as + well.) @style{wxTR_LINES_AT_ROOT} - Use this style to show lines between root nodes. Only applicable if - wxTR_HIDE_ROOT is set and wxTR_NO_LINES is not set. + Use this style to show lines between root nodes. Only applicable if @c + wxTR_HIDE_ROOT is set and @c wxTR_NO_LINES is not set. @style{wxTR_HIDE_ROOT} - Use this style to suppress the display of the root node, - effectively causing the first-level nodes to appear as a series of - root nodes. + Use this style to suppress the display of the root node, effectively + causing the first-level nodes to appear as a series of root nodes. @style{wxTR_ROW_LINES} - Use this style to draw a contrasting border between displayed rows. + Use this style to draw a contrasting border between displayed rows. @style{wxTR_HAS_VARIABLE_ROW_HEIGHT} - Use this style to cause row heights to be just big enough to fit - the content. If not set, all rows use the largest row height. The - default is that this flag is unset. Generic only. + Use this style to cause row heights to be just big enough to fit the + content. If not set, all rows use the largest row height. The default is + that this flag is unset. Generic only. @style{wxTR_SINGLE} - For convenience to document that only one item may be selected at a - time. Selecting another item causes the current selection, if any, - to be deselected. This is the default. + For convenience to document that only one item may be selected at a + time. Selecting another item causes the current selection, if any, to be + deselected. This is the default. @style{wxTR_MULTIPLE} - Use this style to allow a range of items to be selected. If a - second range is selected, the current range, if any, is deselected. + Use this style to allow a range of items to be selected. If a second + range is selected, the current range, if any, is deselected. @style{wxTR_DEFAULT_STYLE} - The set of flags that are closest to the defaults for the native - control for a particular toolkit. + The set of flags that are closest to the defaults for the native control + for a particular toolkit. @endStyleTable + See also @ref overview_windowstyles. + + @b Win32 @b notes: + + wxTreeCtrl class uses the standard common treeview control under Win32 + implemented in the system library comctl32.dll. Some versions of this + library are known to have bugs with handling the tree control colours: the + usual symptom is that the expanded items leave black (or otherwise + incorrectly coloured) background behind them, especially for the controls + using non-default background colour. The recommended solution is to upgrade + the comctl32.dll to a newer version: see + http://www.microsoft.com/downloads/details.aspx?familyid=cb2cf3a2-8025-4e8f-8511-9b476a8d35d2 + @library{wxcore} @category{ctrl} - @see wxTreeItemData, @ref overview_wxtreectrloverview "wxTreeCtrl overview", - wxListBox, wxListCtrl, wxImageList, wxTreeEvent + @see wxTreeEvent, wxTreeItemData, @ref overview_treectrl, wxListBox, + wxListCtrl, wxImageList */ class wxTreeCtrl : public wxControl { public: - //@{ + /** + Default Constructor. + */ + wxTreeCtrl(); + /** Constructor, creating and showing a tree control. @param parent Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. + Window identifier. The value @c wxID_ANY indicates a default value. @param pos Window position. @param size - Window size. If wxDefaultSize is specified then the window is - sized + Window size. If wxDefaultSize is specified then the window is sized appropriately. @param style Window style. See wxTreeCtrl. @@ -152,14 +107,13 @@ public: @see Create(), wxValidator */ - wxTreeCtrl(); wxTreeCtrl(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxTR_HAS_BUTTONS, const wxValidator& validator = wxDefaultValidator, const wxString& name = "treeCtrl"); - //@} + /** Destructor, destroying the tree control. @@ -168,24 +122,24 @@ public: /** Adds the root node to the tree, returning the new item. - The @a image and @a selImage parameters are an index within - the normal image list specifying the image to use for unselected and - selected items, respectively. - If @a image -1 and @a selImage is -1, the same image is used for - both selected and unselected items. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. */ wxTreeItemId AddRoot(const wxString& text, int image = -1, int selImage = -1, wxTreeItemData* data = NULL); /** - Appends an item to the end of the branch identified by @e parent, return a new - item id. - The @a image and @a selImage parameters are an index within - the normal image list specifying the image to use for unselected and - selected items, respectively. - If @a image -1 and @a selImage is -1, the same image is used for - both selected and unselected items. + Appends an item to the end of the branch identified by @a parent, return + a new item id. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. */ wxTreeItemId AppendItem(const wxTreeItemId& parent, const wxString& text, @@ -194,30 +148,35 @@ public: wxTreeItemData* data = NULL); /** - Sets the buttons image list. The button images assigned with this method will - be automatically deleted by wxTreeCtrl as appropriate - (i.e. it takes ownership of the list). - Setting or assigning the button image list enables the display of image buttons. - Once enabled, the only way to disable the display of button images is to set - the button image list to @NULL. + Sets the buttons image list. The button images assigned with this method + will be automatically deleted by wxTreeCtrl as appropriate (i.e. it + takes ownership of the list). + + Setting or assigning the button image list enables the display of image + buttons. Once enabled, the only way to disable the display of button + images is to set the button image list to @NULL. + This function is only available in the generic version. - See also SetButtonsImageList(). + + @see SetButtonsImageList(). */ void AssignButtonsImageList(wxImageList* imageList); /** - Sets the normal image list. Image list assigned with this method will - be automatically deleted by wxTreeCtrl as appropriate - (i.e. it takes ownership of the list). - See also SetImageList(). + Sets the normal image list. The image list assigned with this method + will be automatically deleted by wxTreeCtrl as appropriate (i.e. it + takes ownership of the list). + + @see SetImageList(). */ void AssignImageList(wxImageList* imageList); /** - Sets the state image list. Image list assigned with this method will - be automatically deleted by wxTreeCtrl as appropriate - (i.e. it takes ownership of the list). - See also SetStateImageList(). + Sets the state image list. Image list assigned with this method will be + automatically deleted by wxTreeCtrl as appropriate (i.e. it takes + ownership of the list). + + @see SetStateImageList(). */ void AssignStateImageList(wxImageList* imageList); @@ -246,54 +205,59 @@ public: void CollapseAndReset(const wxTreeItemId& item); /** - Creates the tree control. See wxTreeCtrl() for further details. + Creates the tree control. See wxTreeCtrl::wxTreeCtrl() for further + details. */ - bool wxTreeCtrl(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxTR_HAS_BUTTONS, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "treeCtrl"); + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTR_HAS_BUTTONS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "treeCtrl"); /** - Deletes the specified item. A @c EVT_TREE_DELETE_ITEM event will be + Deletes the specified item. A EVT_TREE_DELETE_ITEM() event will be generated. - This function may cause a subsequent call to GetNextChild to fail. + + This function may cause a subsequent call to GetNextChild() to fail. */ void Delete(const wxTreeItemId& item); /** Deletes all items in the control. Note that this may not generate - @c EVT_TREE_DELETE_ITEM events under some Windows versions although + EVT_TREE_DELETE_ITEM() events under some Windows versions although normally such event is generated for each removed item. */ void DeleteAllItems(); /** - Deletes all children of the given item (but not the item itself). Note that - this will @b not generate any events unlike - Delete() method. - If you have called SetItemHasChildren(), you - may need to call it again since @e DeleteChildren does not automatically - clear the setting. + Deletes all children of the given item (but not the item itself). Note + that this will @b not generate any events unlike Delete() method. + + If you have called SetItemHasChildren(), you may need to call it again + since DeleteChildren() does not automatically clear the setting. */ void DeleteChildren(const wxTreeItemId& item); /** - Starts editing the label of the given item. This function generates a - EVT_TREE_BEGIN_LABEL_EDIT event which can be vetoed so that no - text control will appear for in-place editing. - If the user changed the label (i.e. s/he does not press ESC or leave - the text control without changes, a EVT_TREE_END_LABEL_EDIT event - will be sent which can be vetoed as well. + Starts editing the label of the given @a item. This function generates a + EVT_TREE_BEGIN_LABEL_EDIT() event which can be vetoed so that no text + control will appear for in-place editing. + + If the user changed the label (i.e. s/he does not press ESC or leave the + text control without changes, a EVT_TREE_END_LABEL_EDIT() event will be + sent which can be vetoed as well. @see EndEditLabel(), wxTreeEvent */ void EditLabel(const wxTreeItemId& item); /** - Ends label editing. If @a cancelEdit is @true, the edit will be cancelled. - This function is currently supported under Windows only. + Ends label editing. If @a cancelEdit is @true, the edit will be + cancelled. + + @note + This function is currently supported under Windows only. @see EditLabel() */ @@ -320,31 +284,39 @@ public: void ExpandAllChildren(const wxTreeItemId& item); /** - Retrieves the rectangle bounding the @e item. If @a textOnly is @true, - only the rectangle around the item's label will be returned, otherwise the - item's image is also taken into account. - The return value is @true if the rectangle was successfully retrieved or @c - @false - if it was not (in this case @a rect is not changed) -- for example, if the - item is currently invisible. - Notice that the rectangle coordinates are logical, not physical ones. So, for - example, the x coordinate may be negative if the tree has a horizontal - scrollbar and its position is not 0. + Retrieves the rectangle bounding the @a item. If @a textOnly is @true, + only the rectangle around the item's label will be returned, otherwise + the item's image is also taken into account. + + The return value is @true if the rectangle was successfully retrieved or + @c @false if it was not (in this case @a rect is not changed) -- for + example, if the item is currently invisible. + + Notice that the rectangle coordinates are logical, not physical ones. + So, for example, the x coordinate may be negative if the tree has a + horizontal scrollbar and its position is not 0. + + @beginWxPythonOnly + The wxPython version of this method requires only the @a item and @a + textOnly parameters. The return value is either a wxRect object or @c + None. + @endWxPythonOnly */ bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect, bool textOnly = false) const; /** - Returns the buttons image list (from which application-defined button images - are taken). + Returns the buttons image list (from which application-defined button + images are taken). + This function is only available in the generic version. */ wxImageList* GetButtonsImageList() const; /** Returns the number of items in the branch. If @a recursively is @true, - returns the total number - of descendants, otherwise only one level of children is counted. + returns the total number of descendants, otherwise only one level of + children is counted. */ unsigned int GetChildrenCount(const wxTreeItemId& item, bool recursively = true) const; @@ -355,21 +327,29 @@ public: unsigned int GetCount() const; /** - Returns the edit control being currently used to edit a label. Returns @NULL - if no label is being edited. - @note It is currently only implemented for wxMSW. + Returns the edit control being currently used to edit a label. Returns + @NULL if no label is being edited. + + @note This is currently only implemented for wxMSW. */ wxTextCtrl* GetEditControl() const; /** Returns the first child; call GetNextChild() for the next child. + For this enumeration function you must pass in a 'cookie' parameter - which is opaque for the application but is necessary for the library - to make these functions reentrant (i.e. allow more than one - enumeration on one and the same object simultaneously). The cookie passed to - GetFirstChild and GetNextChild should be the same variable. - Returns an invalid tree item (i.e. IsOk() returns @false) if there are no - further children. + which is opaque for the application but is necessary for the library to + make these functions reentrant (i.e. allow more than one enumeration on + one and the same object simultaneously). The cookie passed to + GetFirstChild() and GetNextChild() should be the same variable. + + Returns an invalid tree item (i.e. wxTreeItemId::IsOk() returns @false) + if there are no further children. + + @beginWxPythonOnly + In wxPython the returned wxTreeItemId and the new cookie value are both + returned as a tuple containing the two values. + @endWxPythonOnly @see GetNextChild(), GetNextSibling() */ @@ -396,9 +376,8 @@ public: */ wxColour GetItemBackgroundColour(const wxTreeItemId& item) const; - //@{ /** - Returns the font of the item label. + Returns the tree item data associated with the item. @see wxTreeItemData @@ -409,19 +388,23 @@ public: @endWxPythonOnly */ wxTreeItemData* GetItemData(const wxTreeItemId& item) const; - wxFont GetItemFont(const wxTreeItemId& item) const; - //@} + + /** + Returns the font of the item label. + */ + wxFont GetItemFont(const wxTreeItemId& item) const; /** Gets the specified item image. The value of @a which may be: - wxTreeItemIcon_Normal to get the normal item image - wxTreeItemIcon_Selected to get the selected item image (i.e. the image - which is shown when the item is currently selected) - wxTreeItemIcon_Expanded to get the expanded image (this only - makes sense for items which have children - then this image is shown when the - item is expanded and the normal image is shown when it is collapsed) - wxTreeItemIcon_SelectedExpanded to get the selected expanded image - (which is shown when an expanded item is currently selected) + - ::wxTreeItemIcon_Normal: to get the normal item image. + - ::wxTreeItemIcon_Selected: to get the selected item image (i.e. the + image which is shown when the item is currently selected). + - ::wxTreeItemIcon_Expanded: to get the expanded image (this only makes + sense for items which have children - then this image is shown when + the item is expanded and the normal image is shown when it is + collapsed). + - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image + (which is shown when an expanded item is currently selected). */ int GetItemImage(const wxTreeItemId& item, wxTreeItemIcon which = wxTreeItemIcon_Normal) const; @@ -432,8 +415,9 @@ public: wxTreeItemId GetItemParent(const wxTreeItemId& item) const; /** - Gets the selected item image (this function is obsolete, use - @c GetItemImage(item, wxTreeItemIcon_Selected) instead). + Gets the selected item image (this function is obsolete, use @ref + GetItemImage() "GetItemImage"( @a item, ::wxTreeItemIcon_Selected) + instead). */ int GetItemSelectedImage(const wxTreeItemId& item) const; @@ -448,31 +432,37 @@ public: wxColour GetItemTextColour(const wxTreeItemId& item) const; /** - Returns the last child of the item (or an invalid tree item if this item has no - children). + Returns the last child of the item (or an invalid tree item if this item + has no children). - @see GetFirstChild(), GetNextSibling(), - GetLastChild() + @see GetFirstChild(), GetNextSibling(), GetLastChild() */ wxTreeItemId GetLastChild(const wxTreeItemId& item) const; /** - Returns the next child; call GetFirstChild() for the first child. - For this enumeration function you must pass in a 'cookie' parameter - which is opaque for the application but is necessary for the library - to make these functions reentrant (i.e. allow more than one - enumeration on one and the same object simultaneously). The cookie passed to - GetFirstChild and GetNextChild should be the same. + Returns the next child; call GetFirstChild() for the first child. For + this enumeration function you must pass in a 'cookie' parameter which is + opaque for the application but is necessary for the library to make + these functions reentrant (i.e. allow more than one enumeration on one + and the same object simultaneously). The cookie passed to + GetFirstChild() and GetNextChild() should be the same. + Returns an invalid tree item if there are no further children. + @beginWxPythonOnly + In wxPython the returned wxTreeItemId and the new cookie value are both + returned as a tuple containing the two values. + @endWxPythonOnly + @see GetFirstChild() */ wxTreeItemId GetNextChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const; /** - Returns the next sibling of the specified item; call GetPrevSibling() for the - previous sibling. + Returns the next sibling of the specified item; call GetPrevSibling() + for the previous sibling. + Returns an invalid tree item if there are no further siblings. @see GetPrevSibling() @@ -480,15 +470,17 @@ public: wxTreeItemId GetNextSibling(const wxTreeItemId& item) const; /** - Returns the next visible item or an invalid item if this item is the last - visible one. - Notice that the @a item itself must be visible. + Returns the next visible item or an invalid item if this item is the + last visible one. + + @note The @a item itself must be visible. */ wxTreeItemId GetNextVisible(const wxTreeItemId& item) const; /** - Returns the previous sibling of the specified item; call GetNextSibling() for - the next sibling. + Returns the previous sibling of the specified item; call + GetNextSibling() for the next sibling. + Returns an invalid tree item if there are no further children. @see GetNextSibling() @@ -496,15 +488,16 @@ public: wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const; /** - Returns the previous visible item or an invalid item if this item is the first - visible one. - Notice that the @a item itself must be visible. + Returns the previous visible item or an invalid item if this item is the + first visible one. + + @note The @a item itself must be visible. */ wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const; /** - Returns @true if the control will use a quick calculation for the best size, - looking only at the first and last items. The default is @false. + Returns @true if the control will use a quick calculation for the best + size, looking only at the first and last items. The default is @false. @see SetQuickBestSize() */ @@ -516,87 +509,66 @@ public: wxTreeItemId GetRootItem() const; /** - Returns the selection, or an invalid item if there is no selection. - This function only works with the controls without wxTR_MULTIPLE style, use - GetSelections() for the controls which do have - this style. + Returns the selection, or an invalid item if there is no selection. This + function only works with the controls without @c wxTR_MULTIPLE style, + use GetSelections() for the controls which do have this style. */ wxTreeItemId GetSelection() const; /** - Fills the array of tree items passed in with the currently selected items. This - function can be called only if the control has the wxTR_MULTIPLE style. + Fills the array of tree items passed in with the currently selected + items. This function can be called only if the control has the @c + wxTR_MULTIPLE style. + Returns the number of selected items. + + @beginWxPythonOnly + The wxPython version of this method accepts no parameters and returns a + Python list of @ref wxTreeItemId "wxTreeItemId"s. + @endWxPythonOnly */ unsigned int GetSelections(wxArrayTreeItemIds& selection) const; /** - Returns the state image list (from which application-defined state images are - taken). + Returns the state image list (from which application-defined state + images are taken). */ wxImageList* GetStateImageList() const; /** - Calculates which (if any) item is under the given point, returning the tree item - id at this point plus extra information @e flags. @a flags is a bitlist of the - following: - - wxTREE_HITTEST_ABOVE - - Above the client area. - - wxTREE_HITTEST_BELOW - - Below the client area. - - wxTREE_HITTEST_NOWHERE - - In the client area but below the last item. - - wxTREE_HITTEST_ONITEMBUTTON - - On the button associated with an item. - - wxTREE_HITTEST_ONITEMICON - - On the bitmap associated with an item. - - wxTREE_HITTEST_ONITEMINDENT - - In the indentation associated with an item. - - wxTREE_HITTEST_ONITEMLABEL - - On the label (string) associated with an item. - - wxTREE_HITTEST_ONITEMRIGHT - - In the area to the right of an item. - - wxTREE_HITTEST_ONITEMSTATEICON - - On the state icon for a tree view item that is in a user-defined state. - - wxTREE_HITTEST_TOLEFT - - To the right of the client area. - - wxTREE_HITTEST_TORIGHT - - To the left of the client area. + Calculates which (if any) item is under the given @a point, returning + the tree item id at this point plus extra information @a flags. @a flags + is a bitlist of the following: + + - @c wxTREE_HITTEST_ABOVE: Above the client area. + - @c wxTREE_HITTEST_BELOW: Below the client area. + - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item. + - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item. + - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item. + - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an + item. + - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with + an item. + - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item. + - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view + item that is in a user-defined state. + - @c wxTREE_HITTEST_TOLEFT: To the right of the client area. + - @c wxTREE_HITTEST_TORIGHT: To the left of the client area. + + @beginWxPythonOnly + In wxPython both the wxTreeItemId and the flags are returned as a tuple. + @endWxPythonOnly */ wxTreeItemId HitTest(const wxPoint& point, int& flags) const; - //@{ + /** - Inserts an item after a given one (@e previous) or before one identified by its - position (@e before). - @a before must be less than the number of children. - The @a image and @a selImage parameters are an index within - the normal image list specifying the image to use for unselected and - selected items, respectively. - If @a image -1 and @a selImage is -1, the same image is used for - both selected and unselected items. + Inserts an item after a given one (@a previous). + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. */ wxTreeItemId InsertItem(const wxTreeItemId& parent, const wxTreeItemId& previous, @@ -604,27 +576,44 @@ public: int image = -1, int selImage = -1, wxTreeItemData* data = NULL); + + /** + Inserts an item before one identified + by its position (@a before). @a before must be less than the number of + children. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. + + @beginWxPythonOnly + In wxPython, this form of this method is called @c InsertItemBefore(). + @endWxPythonOnly + */ wxTreeItemId InsertItem(const wxTreeItemId& parent, size_t before, const wxString& text, int image = -1, int selImage = -1, wxTreeItemData* data = NULL); - //@} /** Returns @true if the given item is in bold state. - See also: SetItemBold() + + @see SetItemBold() */ bool IsBold(const wxTreeItemId& item) const; /** - Returns @true if the control is empty (i.e. has no items, even no root one). + Returns @true if the control is empty (i.e. has no items, even no root + one). */ bool IsEmpty() const; /** - Returns @true if the item is expanded (only makes sense if it has children). + Returns @true if the item is expanded (only makes sense if it has + children). */ bool IsExpanded(const wxTreeItemId& item) const; @@ -644,28 +633,29 @@ public: bool ItemHasChildren(const wxTreeItemId& item) const; /** - Override this function in the derived class to change the sort order of the - items in the tree control. The function should return a negative, zero or - positive value if the first item is less than, equal to or greater than the - second one. - Please note that you @b must use wxRTTI macros - DECLARE_DYNAMIC_CLASS() and - IMPLEMENT_DYNAMIC_CLASS() if you override this - function because otherwise the base class considers that it is not overridden - and uses the default comparison, i.e. sorts the items alphabetically, which + Override this function in the derived class to change the sort order of + the items in the tree control. The function should return a negative, + zero or positive value if the first item is less than, equal to or + greater than the second one. + + Please note that you @b must use wxRTTI macros DECLARE_DYNAMIC_CLASS() + and IMPLEMENT_DYNAMIC_CLASS() if you override this function because + otherwise the base class considers that it is not overridden and uses + the default comparison, i.e. sorts the items alphabetically, which allows it optimize away the calls to the virtual function completely. - See also: SortChildren() + + @see SortChildren() */ int OnCompareItems(const wxTreeItemId& item1, const wxTreeItemId& item2); /** - Appends an item as the first child of @e parent, return a new item id. - The @a image and @a selImage parameters are an index within - the normal image list specifying the image to use for unselected and - selected items, respectively. - If @a image -1 and @a selImage is -1, the same image is used for - both selected and unselected items. + Appends an item as the first child of @a parent, return a new item id. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. */ wxTreeItemId PrependItem(const wxTreeItemId& parent, const wxString& text, @@ -679,28 +669,34 @@ public: void ScrollTo(const wxTreeItemId& item); /** - Selects the given item. In multiple selection controls, can be also used to - deselect a currently selected item if the value of @a select is @false. + Selects the given item. In multiple selection controls, can be also used + to deselect a currently selected item if the value of @a select is + @false. */ void SelectItem(const wxTreeItemId& item, bool select = true); /** - Sets the buttons image list (from which application-defined button images are - taken). - The button images assigned with this method will - @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. - Setting or assigning the button image list enables the display of image buttons. - Once enabled, the only way to disable the display of button images is to set - the button image list to @NULL. - This function is only available in the generic version. - See also AssignButtonsImageList(). + Sets the buttons image list (from which application-defined button + images are taken). + + The button images assigned with this method will @b not be deleted by + @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself. + Setting or assigning the button image list enables the display of image + buttons. Once enabled, the only way to disable the display of button + images is to set the button image list to @NULL. + + @note This function is only available in the generic version. + + @see AssignButtonsImageList(). */ void SetButtonsImageList(wxImageList* imageList); /** - Sets the normal image list. Image list assigned with this method will - @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. - See also AssignImageList(). + Sets the normal image list. The image list assigned with this method + will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you + must delete it yourself. + + @see AssignImageList(). */ void SetImageList(wxImageList* imageList); @@ -716,43 +712,38 @@ public: const wxColour& col); /** - Makes item appear in bold font if @a bold parameter is @true or resets it to - the normal state. - See also: IsBold() + Makes item appear in bold font if @a bold parameter is @true or resets + it to the normal state. + + @see IsBold() */ void SetItemBold(const wxTreeItemId& item, bool bold = true); - //@{ + /** + Sets the item client data. + + @beginWxPythonOnly + - @b SetPyData( @a item, @c obj): Associate the given Python Object with + the wxTreeItemData for the given item Id. + @endWxPythonOnly + + */ + void SetItemData(const wxTreeItemId& item, wxTreeItemData* data); + + /** Gives the item the visual feedback for Drag'n'Drop actions, which is useful if something is dragged from the outside onto the tree control (as opposed to a DnD operation within the tree control, which already is implemented internally). */ - void SetItemData(const wxTreeItemId& item, wxTreeItemData* data); -wxPython note: - SetPyData(item, obj) - - - - - Associate the given Python - Object with the wxTreeItemData for the given item Id. - - - - - - - void SetItemDropHighlight(const wxTreeItemId& item, bool highlight = true); - //@} /** - Sets the item's font. All items in the tree should have the same height to avoid - text clipping, so the fonts height should be the same for all of them, - although font attributes may vary. + Sets the item's font. All items in the tree should have the same height + to avoid text clipping, so the fonts height should be the same for all + of them, although font attributes may vary. @see SetItemBold() */ @@ -768,15 +759,16 @@ wxPython note: bool hasChildren = true); /** - Sets the specified item image. See GetItemImage() - for the description of the @a which parameter. + Sets the specified item's image. See GetItemImage() for the description + of the @a which parameter. */ void SetItemImage(const wxTreeItemId& item, int image, wxTreeItemIcon which = wxTreeItemIcon_Normal); /** - Sets the selected item image (this function is obsolete, use - @c SetItemImage(item, wxTreeItemIcon_Selected) instead). + Sets the selected item image (this function is obsolete, use @ref + SetItemImage() "SetItemImage"( @a item, ::wxTreeItemIcon_Selected ) + instead). */ void SetItemSelectedImage(const wxTreeItemId& item, int selImage); @@ -792,36 +784,36 @@ wxPython note: const wxColour& col); /** - If @true is passed, specifies that the control will use a quick calculation for - the best size, - looking only at the first and last items. Otherwise, it will look at all items. - The default is @false. + If @true is passed, specifies that the control will use a quick + calculation for the best size, looking only at the first and last items. + Otherwise, it will look at all items. The default is @false. @see GetQuickBestSize() */ void SetQuickBestSize(bool quickBestSize); /** - Sets the state image list (from which application-defined state images are - taken). - Image list assigned with this method will - @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. - See also AssignStateImageList(). + Sets the state image list (from which application-defined state images + are taken). Image list assigned with this method will @b not be deleted + by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it + yourself. + + @see AssignStateImageList(). */ void SetStateImageList(wxImageList* imageList); /** - Sets the mode flags associated with the display of the tree control. - The new mode takes effect immediately. - (Generic only; MSW ignores changes.) + Sets the mode flags associated with the display of the tree control. The + new mode takes effect immediately. + + @note Generic only; MSW ignores changes. */ void SetWindowStyle(long styles); /** - Sorts the children of the given item using - OnCompareItems() method of wxTreeCtrl. You - should override that method to change the sort order (the default is ascending - case-sensitive alphabetical order). + Sorts the children of the given item using OnCompareItems(). + You should override that method to change the sort order (the default is + ascending case-sensitive alphabetical order). @see wxTreeItemData, OnCompareItems() */ @@ -844,9 +836,9 @@ wxPython note: void Unselect(); /** - This function either behaves the same as Unselect() - if the control doesn't have wxTR_MULTIPLE style, or removes the selection from - all items if it does have this style. + This function either behaves the same as Unselect() if the control + doesn't have @c wxTR_MULTIPLE style, or removes the selection from all + items if it does have this style. */ void UnselectAll(); @@ -862,7 +854,59 @@ wxPython note: @class wxTreeEvent @wxheader{treectrl.h} - A tree event holds information about events associated with wxTreeCtrl objects. + A tree event holds information about events associated with wxTreeCtrl + objects. + + To process input from a tree control, use these event handler macros to + direct input to member functions that take a wxTreeEvent argument. + + @beginEventTable{wxTreeEvent} + @event{EVT_TREE_BEGIN_DRAG(id, func)} + Begin dragging with the left mouse button. + @event{EVT_TREE_BEGIN_RDRAG(id, func)} + Begin dragging with the right mouse button. + @event{EVT_TREE_END_DRAG(id, func)} + End dragging with the left or right mouse button. + @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)} + Begin editing a label. This can be prevented by calling Veto(). + @event{EVT_TREE_END_LABEL_EDIT(id, func)} + Finish editing a label. This can be prevented by calling Veto(). + @event{EVT_TREE_DELETE_ITEM(id, func)} + Delete an item. + @event{EVT_TREE_GET_INFO(id, func)} + Request information from the application. + @event{EVT_TREE_SET_INFO(id, func)} + Information is being supplied. + @event{EVT_TREE_ITEM_ACTIVATED(id, func)} + The item has been activated, i.e. chosen by double clicking it with + mouse or from keyboard. + @event{EVT_TREE_ITEM_COLLAPSED(id, func)} + The item has been collapsed. + @event{EVT_TREE_ITEM_COLLAPSING(id, func)} + The item is being collapsed. This can be prevented by calling Veto(). + @event{EVT_TREE_ITEM_EXPANDED(id, func)} + The item has been expanded. + @event{EVT_TREE_ITEM_EXPANDING(id, func)} + The item is being expanded. This can be prevented by calling Veto(). + @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)} + The user has clicked the item with the right mouse button. + @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)} + The user has clicked the item with the middle mouse button. + @event{EVT_TREE_SEL_CHANGED(id, func)} + Selection has changed. + @event{EVT_TREE_SEL_CHANGING(id, func)} + Selection is changing. This can be prevented by calling Veto(). + @event{EVT_TREE_KEY_DOWN(id, func)} + A key has been pressed. + @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)} + The opportunity to set the item tooltip is being given to the + application (call SetToolTip()). Windows only. + @event{EVT_TREE_ITEM_MENU(id, func)} + The context menu for the selected item has been requested, either by a + right click or by using the menu key. + @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)} + The state image has been clicked. Windows only. + @endEventTable @library{wxbase} @category{events} @@ -873,7 +917,6 @@ class wxTreeEvent : public wxNotifyEvent { public: /** - ) Constructor, used by wxWidgets itself only. */ wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree); @@ -884,14 +927,13 @@ public: wxTreeItemId GetItem() const; /** - Returns the key code if the event is a key event. Use - GetKeyEvent() to get the values of the - modifier keys for this event (i.e. Shift or Ctrl). + Returns the key code if the event is a key event. Use GetKeyEvent() to + get the values of the modifier keys for this event (i.e. Shift or Ctrl). */ int GetKeyCode() const; /** - Returns the key event for @c EVT_TREE_KEY_DOWN events. + Returns the key event for EVT_TREE_KEY_DOWN() events. */ const wxKeyEvent GetKeyEvent() const; @@ -901,28 +943,30 @@ public: const wxString GetLabel() const; /** - Returns the old item index (valid for EVT_TREE_ITEM_CHANGING and CHANGED events) + Returns the old item index (valid for EVT_TREE_ITEM_CHANGING() and + EVT_TREE_ITEM_CHANGED() events). */ wxTreeItemId GetOldItem() const; /** Returns the position of the mouse pointer if the event is a drag or menu-context event. - In both cases the position is in client coordinates - i.e. relative to the - wxTreeCtrl - window (so that you can pass it directly to e.g. wxWindow::PopupMenu). + + In both cases the position is in client coordinates - i.e. relative to + the wxTreeCtrl window (so that you can pass it directly to e.g. + wxWindow::PopupMenu()). */ wxPoint GetPoint() const; /** - Returns @true if the label edit was cancelled. This should be - called from within an EVT_TREE_END_LABEL_EDIT handler. + Returns @true if the label edit was cancelled. This should be called + from within an EVT_TREE_END_LABEL_EDIT() handler. */ bool IsEditCancelled() const; /** - Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP events). - Windows only. + Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP() + events). Windows only. */ void SetToolTip(const wxString& tooltip); }; diff --git a/interface/txtstrm.h b/interface/txtstrm.h index 7a126a3a1e..83ab454d9b 100644 --- a/interface/txtstrm.h +++ b/interface/txtstrm.h @@ -6,57 +6,56 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + + /** @class wxTextInputStream @wxheader{txtstrm.h} - This class provides functions that read text datas using an input stream. - So, you can read @e text floats, integers. - - The wxTextInputStream correctly reads text files (or streams) in DOS, Macintosh - and Unix formats and reports a single newline char as a line ending. - - Operator is overloaded and you can use this class like a standard C++ iostream. - Note, however, that the arguments are the fixed size types wxUint32, wxInt32 etc - and on a typical 32-bit computer, none of these match to the "long" type - (wxInt32 - is defined as int on 32-bit architectures) so that you cannot use long. To avoid - problems (here and elsewhere), make use of wxInt32, wxUint32 and similar types. - - If you're scanning through a file using wxTextInputStream, you should check for - EOF @b before - reading the next item (word / number), because otherwise the last item may get - lost. - You should however be prepared to receive an empty item (empty string / zero - number) at the - end of file, especially on Windows systems. This is unavoidable because most - (but not all) files end - with whitespace (i.e. usually a newline). + This class provides functions that reads text data using an input stream, + allowing you to read text, floats, and integers. + + The wxTextInputStream correctly reads text files (or streams) in DOS, + Macintosh and Unix formats and reports a single newline char as a line + ending. + + wxTextInputStream::operator>>() is overloaded and you can use this class + like a standard C++ iostream. Note, however, that the arguments are the + fixed size types wxUint32, wxInt32 etc and on a typical 32-bit computer, + none of these match to the "long" type (wxInt32 is defined as int on 32-bit + architectures) so that you cannot use long. To avoid problems (here and + elsewhere), make use of wxInt32, wxUint32 and similar types. + + If you're scanning through a file using wxTextInputStream, you should check + for @c EOF @b before reading the next item (word / number), because + otherwise the last item may get lost. You should however be prepared to + receive an empty item (empty string / zero number) at the end of file, + especially on Windows systems. This is unavoidable because most (but not + all) files end with whitespace (i.e. usually a newline). For example: @code wxFileInputStream input( "mytext.txt" ); - wxTextInputStream text( input ); - wxUint8 i1; - float f2; - wxString line; - - text i1; // read a 8 bit integer. - text i1 f2; // read a 8 bit integer followed by float. - text line; // read a text line + wxTextInputStream text( input ); + wxUint8 i1; + float f2; + wxString line; + + text >> i1; // read a 8 bit integer. + text >> i1 >> f2; // read a 8 bit integer followed by float. + text >> line; // read a text line @endcode @library{wxbase} @category{streams} - @see wxTextInputStream::SetStringSeparators + @see wxTextOutputStream */ class wxTextInputStream { public: /** - ) Constructs a text stream associated to the given input stream. @param stream @@ -64,67 +63,69 @@ public: @param sep The initial string separator characters. @param conv - In Unicode build only: The encoding converter used to convert the bytes in - the - underlying input stream to characters. + In Unicode build only: The encoding converter used to + convert the bytes in the underlying input stream to characters. */ wxTextInputStream(wxInputStream& stream, - const wxString& sep = " \t"); + const wxString& sep = " \t", + const wxMBConv& conv = wxConvAuto()); /** - Destroys the wxTextInputStream object. + Destructor. */ ~wxTextInputStream(); /** - Reads a character, returns 0 if there are no more characters in the stream. + Reads a character, returns 0 if there are no more characters in the + stream. */ wxChar GetChar(); /** Reads a unsigned 16 bit integer from the stream. - See wxTextInputStream::Read8 for the - description of the @a base parameter. + + See Read8() for the description of the @a base parameter. */ wxUint16 Read16(int base = 10); /** Reads a signed 16 bit integer from the stream. - See wxTextInputStream::Read8 for the - description of the @a base parameter. + + See Read8() for the description of the @a base parameter. */ wxInt16 Read16S(int base = 10); /** Reads a 32 bit unsigned integer from the stream. - See wxTextInputStream::Read8 for the - description of the @a base parameter. + + See Read8() for the description of the @a base parameter. */ wxUint32 Read32(int base = 10); /** Reads a 32 bit signed integer from the stream. - See wxTextInputStream::Read8 for the - description of the @a base parameter. + + See Read8() for the description of the @a base parameter. */ wxInt32 Read32S(int base = 10); /** - Reads a single unsigned byte from the stream, given in base @e base. + Reads a single unsigned byte from the stream, given in base @a base. + The value of @a base must be comprised between 2 and 36, inclusive, or - be a special value 0 which means that the usual rules of @c C numbers are + be a special value 0 which means that the usual rules of C numbers are applied: if the number starts with @c 0x it is considered to be in base - 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note - that you may not want to specify the base 0 if you are parsing the numbers - which may have leading zeroes as they can yield unexpected (to the user not - familiar with C) results. + 16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that + you may not want to specify the base 0 if you are parsing the numbers + which may have leading zeroes as they can yield unexpected (to the user + not familiar with C) results. */ wxUint8 Read8(int base = 10); /** Reads a single signed byte from the stream. - See wxTextInputStream::Read8 for the - description of the @a base parameter. + + See Read8() for the description of the @a base parameter. */ wxInt8 Read8S(int base = 10); @@ -134,21 +135,21 @@ public: double ReadDouble(); /** - Reads a line from the input stream and returns it (without the end of line - character). + Reads a line from the input stream and returns it (without the end of + line character). */ wxString ReadLine(); /** - @note This method is deprecated, use ReadLine() - or ReadWord() instead. + @deprecated Use ReadLine() or ReadWord() instead. + Same as ReadLine(). */ wxString ReadString(); /** - Reads a word (a sequence of characters until the next separator) from the - input stream. + Reads a word (a sequence of characters until the next separator) from + the input stream. @see SetStringSeparators() */ @@ -157,55 +158,84 @@ public: /** Sets the characters which are used to define the word boundaries in ReadWord(). - The default separators are the space and @c TAB characters. + + The default separators are the @c space and @c TAB characters. */ void SetStringSeparators(const wxString& sep); }; +/** + Specifies the end-of-line characters to use with wxTextOutputStream. +*/ +typedef enum +{ + /** + Specifies wxTextOutputStream to use the native end-of-line characters. + */ + wxEOL_NATIVE, + + /** + Specifies wxTextOutputStream to use Unix end-of-line characters. + */ + wxEOL_UNIX, + + /** + Specifies wxTextOutputStream to use Mac end-of-line characters. + */ + wxEOL_MAC, + + /** + Specifies wxTextOutputStream to use DOS end-of-line characters. + */ + wxEOL_DOS +} wxEOL; + /** @class wxTextOutputStream @wxheader{txtstrm.h} - This class provides functions that write text datas using an output stream. - So, you can write @e text floats, integers. + This class provides functions that writes text data using an output stream, + allowing you to write text, floats, and integers. You can also simulate the C++ cout class: @code wxFFileOutputStream output( stderr ); - wxTextOutputStream cout( output ); + wxTextOutputStream cout( output ); - cout "This is a text line" endl; - cout 1234; - cout 1.23456; + cout << "This is a text line" << endl; + cout << 1234; + cout << 1.23456; @endcode - The wxTextOutputStream writes text files (or streams) on DOS, Macintosh - and Unix in their native formats (concerning the line ending). + The wxTextOutputStream writes text files (or streams) on DOS, Macintosh and + Unix in their native formats (concerning the line ending). @library{wxbase} @category{streams} + + @see wxTextInputStream */ class wxTextOutputStream { public: /** - ) Constructs a text stream object associated to the given output stream. @param stream The output stream. @param mode - The end-of-line mode. One of wxEOL_NATIVE, wxEOL_DOS, wxEOL_MAC and - wxEOL_UNIX. + The end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS, + ::wxEOL_MAC and ::wxEOL_UNIX. @param conv - In Unicode build only: The object used to convert + In Unicode build only: The object used to convert Unicode text into ASCII characters written to the output stream. */ wxTextOutputStream(wxOutputStream& stream, - wxEOL mode = wxEOL_NATIVE); + wxEOL mode = wxEOL_NATIVE, + const wxMBConv& conv = wxConvAuto()); /** Destroys the wxTextOutputStream object. @@ -213,8 +243,8 @@ public: ~wxTextOutputStream(); /** - Returns the end-of-line mode. One of @b wxEOL_DOS, @b wxEOL_MAC and @b - wxEOL_UNIX. + Returns the end-of-line mode. One of ::wxEOL_DOS, ::wxEOL_MAC and + ::wxEOL_UNIX. */ wxEOL GetMode(); @@ -224,8 +254,8 @@ public: void PutChar(wxChar c); /** - Set the end-of-line mode. One of @b wxEOL_NATIVE, @b wxEOL_DOS, @b wxEOL_MAC - and @b wxEOL_UNIX. + Set the end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS, + ::wxEOL_MAC and ::wxEOL_UNIX. */ void SetMode(wxEOL mode = wxEOL_NATIVE); @@ -251,8 +281,8 @@ public: /** Writes @a string as a line. Depending on the end-of-line mode the end of - line ('\n') characters in the string are converted to the correct - line ending terminator. + line ('\\n') characters in the string are converted to the correct line + ending terminator. */ virtual void WriteString(const wxString& string); }; -- 2.45.2