--- /dev/null
+/////////////////////////////////////////////////////////////////////////////
+// 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:
+
+};
+
@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
class wxToolBar : public wxControl
{
public:
- //@{
+ /**
+ Default constructor.
+ */
+ wxToolBar();
+
/**
Constructs a toolbar.
@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.
~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()
*/
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()
*/
//@{
/**
- 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()
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);
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);
@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;
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()
*/
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;
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()
*/
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()
*/
//@{
/**
- 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()
//@}
/**
- 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().
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);
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
*/
//@}
/**
- 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()
*/
/**
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);
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);
@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()
*/
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()
*/
@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);
};
@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<T> 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<MyClass> MyClassRef;
@endcode
@library{wxbase}
- @category{FIXME}
+ @category{smartpointers}
*/
class wxTrackable
{
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();
//@{
/**
- 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
+};
@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
{
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;
};
@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.
@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,
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);
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,
/**
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,
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);
};
// 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}
<!-- @appearance{treectrl.png} -->
- @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.
@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.
/**
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,
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);
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()
*/
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;
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()
*/
*/
wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
- //@{
/**
- Returns the font of the item label.
+ Returns the tree item data associated with the item.
@see wxTreeItemData
@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;
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;
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()
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()
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()
*/
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,
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;
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,
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);
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()
*/
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);
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()
*/
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();
@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}
{
public:
/**
- )
Constructor, used by wxWidgets itself only.
*/
wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree);
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;
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);
};
// 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
@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.
+ <b>In Unicode build only:</b> 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);
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()
*/
/**
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
+ <b>In Unicode build only:</b> 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.
~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();
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);
/**
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);
};
projects / wxWidgets.git / commitdiff
