[wxWidgets.git] / interface / wx / windowptr.h

///////////////////////////////////////////////////////////////////////////////
// Name:        interface/wx/windowptr.h
// Purpose:     wxWindowPtr<T> class documentation.
// Author:      Vaclav Slavik
// Created:     2013-09-02
// Copyright:   (c) 2013 Vaclav Slavik <vslavik@fastmail.fm>
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

/**
    A reference-counted smart pointer for holding wxWindow instances.

    This specialization of wxSharedPtr<T> is useful for holding
    wxWindow-derived objects. Unlike wxSharedPtr<T> or @c std::shared_ptr<>, it
    doesn't use the delete operator to destroy the value when reference count
    drops to zero, but calls wxWindow::Destroy() to safely destroy the window.

    The template parameter T must be wxWindow or a class derived from it.

    @library{wxcore}
    @category{smartpointers}

    @since 3.0

    @see wxSharedPtr<T>
*/
template<typename T>
class wxWindowPtr<T> : public wxSharedPtr<T>
{
public:
    /// Default constructor.
    wxWindowPtr();

    /**
        Constructor.

        Creates shared pointer from the raw pointer @a ptr and takes ownership
        of it.
    */
    explicit wxWindowPtr(T* ptr);

    /**
        Constructor.

        Creates shared pointer from the raw pointer @a ptr and deleter @a d
        and takes ownership of it.

        @param ptr  The raw pointer.
        @param d    Deleter - a functor that is called instead of delete to
                    free the @a ptr raw pointer when its reference count drops to
                    zero.

    */
    template<typename Deleter>
    explicit wxWindowPtr(T* ptr, Deleter d);

    /// Copy constructor.
    wxWindowPtr(const wxWindowPtr<T>& tocopy);

    /**
        Assignment operator.

        Releases any previously held pointer and creates a reference to @a ptr.
    */
    wxWindowPtr<T>& operator=(T* ptr);

    /**
        Assignment operator.

        Releases any previously held pointer and creates a reference to the
        same object as @a topcopy.
    */
    wxWindowPtr<T>& operator=(const wxWindowPtr<T>& tocopy);

    /**
        Reset pointer to @a ptr.

        If the reference count of the previously owned pointer was 1 it will be deleted.
    */
    void reset(T* ptr = NULL);
};
Commit	Line	Data
c80d4c1e VS	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: interface/wx/windowptr.h
	3	// Purpose: wxWindowPtr<T> class documentation.
	4	// Author: Vaclav Slavik
	5	// Created: 2013-09-02
	6	// Copyright: (c) 2013 Vaclav Slavik <vslavik@fastmail.fm>
	7	// Licence: wxWindows licence
	8	///////////////////////////////////////////////////////////////////////////////
	9
	10	/**
	11	A reference-counted smart pointer for holding wxWindow instances.
	12
	13	This specialization of wxSharedPtr<T> is useful for holding
	14	wxWindow-derived objects. Unlike wxSharedPtr<T> or @c std::shared_ptr<>, it
	15	doesn't use the delete operator to destroy the value when reference count
	16	drops to zero, but calls wxWindow::Destroy() to safely destroy the window.
	17
	18	The template parameter T must be wxWindow or a class derived from it.
	19
	20	@library{wxcore}
	21	@category{smartpointers}
	22
	23	@since 3.0
	24
	25	@see wxSharedPtr<T>
	26	*/
	27	template<typename T>
	28	class wxWindowPtr<T> : public wxSharedPtr<T>
	29	{
	30	public:
	31	/// Default constructor.
	32	wxWindowPtr();
	33
	34	/**
	35	Constructor.
	36
	37	Creates shared pointer from the raw pointer @a ptr and takes ownership
	38	of it.
	39	*/
	40	explicit wxWindowPtr(T* ptr);
	41
	42	/**
	43	Constructor.
	44
	45	Creates shared pointer from the raw pointer @a ptr and deleter @a d
	46	and takes ownership of it.
	47
	48	@param ptr The raw pointer.
	49	@param d Deleter - a functor that is called instead of delete to
	50	free the @a ptr raw pointer when its reference count drops to
	51	zero.
	52
	53	*/
	54	template<typename Deleter>
	55	explicit wxWindowPtr(T* ptr, Deleter d);
	56
	57	/// Copy constructor.
	58	wxWindowPtr(const wxWindowPtr<T>& tocopy);
	59
	60	/**
	61	Assignment operator.
	62
	63	Releases any previously held pointer and creates a reference to @a ptr.
	64	*/
65	wxWindowPtr<T>& operator=(T* ptr);
66
67	/**
68	Assignment operator.
69
70	Releases any previously held pointer and creates a reference to the
71	same object as @a topcopy.
72	*/
73	wxWindowPtr<T>& operator=(const wxWindowPtr<T>& tocopy);
74
75	/**
76	Reset pointer to @a ptr.
77
78	If the reference count of the previously owned pointer was 1 it will be deleted.
79	*/
80	void reset(T* ptr = NULL);
81	};
82